home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 1998 November / IRIX 6.5.2 Base Documentation November 1998.img / usr / share / catman / p_man / cat3 / ifl / TIFFOpen.z / TIFFOpen
Text File  |  1998-10-20  |  17KB  |  263 lines
  1.  
  2.  
  3.  
  4. TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))      IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      TIFFOpen, TIFFFdOpen, TIFFClientOpen - open a TIFF file for reading or
  10.      writing
  11.  
  12. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  13.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttiiiiffffffffiiiioooo....hhhh>>>>
  14.      TTTTIIIIFFFFFFFF**** TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr**** ffffiiiilllleeeennnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr**** mmmmooooddddeeee))))
  15.      TTTTIIIIFFFFFFFF**** TTTTIIIIFFFFFFFFFFFFddddOOOOppppeeeennnn((((ccccoooonnnnsssstttt iiiinnnntttt ffffdddd,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr**** ffffiiiilllleeeennnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr**** mmmmooooddddeeee))))
  16.      ttttyyyyppppeeeeddddeeeeffff ttttssssiiiizzzzeeee____tttt ((((****TTTTIIIIFFFFFFFFRRRReeeeaaaaddddWWWWrrrriiiitttteeeePPPPrrrroooocccc))))((((tttthhhhaaaannnnddddlllleeee____tttt,,,, ttttddddaaaattttaaaa____tttt,,,, ttttssssiiiizzzzeeee____tttt))));;;;
  17.      ttttyyyyppppeeeeddddeeeeffff ttttooooffffffff____tttt ((((****TTTTIIIIFFFFFFFFSSSSeeeeeeeekkkkPPPPrrrroooocccc))))((((tttthhhhaaaannnnddddlllleeee____tttt,,,, ttttooooffffffff____tttt,,,, iiiinnnntttt))));;;;
  18.      ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt ((((****TTTTIIIIFFFFFFFFCCCClllloooosssseeeePPPPrrrroooocccc))))((((tttthhhhaaaannnnddddlllleeee____tttt))));;;;
  19.      ttttyyyyppppeeeeddddeeeeffff ttttooooffffffff____tttt ((((****TTTTIIIIFFFFFFFFSSSSiiiizzzzeeeePPPPrrrroooocccc))))((((tttthhhhaaaannnnddddlllleeee____tttt))));;;;
  20.      ttttyyyyppppeeeeddddeeeeffff iiiinnnntttt ((((****TTTTIIIIFFFFFFFFMMMMaaaappppFFFFiiiilllleeeePPPPrrrroooocccc))))((((tttthhhhaaaannnnddddlllleeee____tttt,,,, ttttddddaaaattttaaaa____tttt****,,,, ttttooooffffffff____tttt****))));;;;
  21.      ttttyyyyppppeeeeddddeeeeffff vvvvooooiiiidddd ((((****TTTTIIIIFFFFFFFFUUUUnnnnmmmmaaaappppFFFFiiiilllleeeePPPPrrrroooocccc))))((((tttthhhhaaaannnnddddlllleeee____tttt,,,, ttttddddaaaattttaaaa____tttt,,,, ttttooooffffffff____tttt))));;;;
  22.      TTTTIIIIFFFFFFFF**** TTTTIIIIFFFFFFFFCCCClllliiiieeeennnnttttOOOOppppeeeennnn((((ccccoooonnnnsssstttt cccchhhhaaaarrrr**** ffffiiiilllleeeennnnaaaammmmeeee,,,, ccccoooonnnnsssstttt cccchhhhaaaarrrr**** mmmmooooddddeeee,,,, tttthhhhaaaannnnddddlllleeee____tttt cccclllliiiieeeennnnttttddddaaaattttaaaa,,,,
  23.          TTTTIIIIFFFFFFFFRRRReeeeaaaaddddWWWWrrrriiiitttteeeePPPPrrrroooocccc rrrreeeeaaaaddddpppprrrroooocccc,,,, TTTTIIIIFFFFFFFFRRRReeeeaaaaddddWWWWrrrriiiitttteeeePPPPrrrroooocccc wwwwrrrriiiitttteeeepppprrrroooocccc,,,, TTTTIIIIFFFFFFFFSSSSeeeeeeeekkkkPPPPrrrroooocccc sssseeeeeeeekkkkpppprrrroooocccc,,,,
  24.          TTTTIIIIFFFFFFFFCCCClllloooosssseeeePPPPrrrroooocccc cccclllloooosssseeeepppprrrroooocccc,,,, TTTTIIIIFFFFFFFFSSSSiiiizzzzeeeePPPPrrrroooocccc ssssiiiizzzzeeeepppprrrroooocccc,,,, TTTTIIIIFFFFFFFFMMMMaaaappppFFFFiiiilllleeeePPPPrrrroooocccc mmmmaaaapppppppprrrroooocccc,,,,
  25.          TTTTIIIIFFFFFFFFUUUUnnnnmmmmaaaappppFFFFiiiilllleeeePPPPrrrroooocccc uuuunnnnmmmmaaaapppppppprrrroooocccc))))
  26.  
  27. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  28.      _T_I_F_F_O_p_e_n opens a TIFF file whose name is _f_i_l_e_n_a_m_e and returns a handle to
  29.      be used in subsequent calls to routines in _l_i_b_t_i_f_f.  If the open
  30.      operation fails, then zero is returned.  The _m_o_d_e parameter specifies if
  31.      the file is to be opened for reading (``r''), writing (``w''), or
  32.      appending (``a'') and, optionally, whether to override certain default
  33.      aspects of library operation (see below).  When a file is opened for
  34.      appending, existing data will not be touched; instead new data will be
  35.      written as additional subfiles.  If an existing file is opened for
  36.      writing, all previous data is overwritten.
  37.  
  38.      If a file is opened for reading, the first TIFF directory in the file is
  39.      automatically read (also see _T_I_F_F_S_e_t_D_i_r_e_c_t_o_r_y(3T) for reading directories
  40.      other than the first).  If a file is opened for writing or appending, a
  41.      default directory is automatically created for writing subsequent data.
  42.      This directory has all the default values specified in TIFF Revision 6.0:
  43.      _B_i_t_s_P_e_r_S_a_m_p_l_e=1, _T_h_r_e_s_h_H_o_l_d_i_n_g=bilevel art scan, _F_i_l_l_O_r_d_e_r=1 (most
  44.      significant bit of each data byte is filled first), _O_r_i_e_n_t_a_t_i_o_n=1 (the
  45.      0th row represents the visual top of the image, and the 0th column
  46.      represents the visual left hand side), _S_a_m_p_l_e_s_P_e_r_P_i_x_e_l=1,
  47.      _R_o_w_s_P_e_r_S_t_r_i_p=infinity, _R_e_s_o_l_u_t_i_o_n_U_n_i_t=2 (inches), and _C_o_m_p_r_e_s_s_i_o_n=1 (no
  48.      compression).  To alter these values, or to define values for additional
  49.      fields, _T_I_F_F_S_e_t_F_i_e_l_d(3T) must be used.
  50.  
  51.      _T_I_F_F_F_d_O_p_e_n is like _T_I_F_F_O_p_e_n except that it opens a TIFF file given an
  52.      open file descriptor _f_d.  The file's name and mode must reflect that of
  53.      the open descriptor.  The object associated with the file descriptor mmmmuuuusssstttt
  54.      ssssuuuuppppppppoooorrrrtttt rrrraaaannnnddddoooommmm aaaacccccccceeeessssssss.
  55.  
  56.  
  57.  
  59.  
  60.  
  61.                                                                         PPPPaaaaggggeeee 1111
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))      IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))
  69.  
  70.  
  71.  
  72.      _T_I_F_F_C_l_i_e_n_t_O_p_e_n is like _T_I_F_F_O_p_e_n except that the caller supplies a
  73.      collection of functions that the library will use to do UNIX-like I/O
  74.      operations. The _r_e_a_d_p_r_o_c and _w_r_i_t_e_p_r_o_c are called to read and write data
  75.      at the current file position.  _s_e_e_k_p_r_o_c is called to change the current
  76.      file position a la _l_s_e_e_k(2).  _c_l_o_s_e_p_r_o_c is invoked to release any
  77.      resources associated with an open file.  _s_i_z_e_p_r_o_c is invoked to obtain
  78.      the size in bytes of a file.  _m_a_p_p_r_o_c and _u_n_m_a_p_p_r_o_c are called to map and
  79.      unmap a file's contents in memory; c.f.  _m_m_a_p(2) and _m_u_n_m_a_p(2).  The
  80.      _c_l_i_e_n_t_d_a_t_a parameter is an opaque ``handle'' passed to the client-
  81.      specified routines passed as parameters to _T_I_F_F_C_l_i_e_n_t_O_p_e_n.
  82.  
  83. OOOOPPPPTTTTIIIIOOOONNNNSSSS
  84.      The open mode parameter can include the following flags in addition to
  85.      the ``r'', ``w'', and ``a'' flags.  Note however that option flags must
  86.      follow the read-write-append specification.
  87.  
  88.      llll    When creating a new file force information be written with Little-
  89.           Endian byte order (but see below).  By default the library will
  90.           create new files using the native CPU byte order.
  91.  
  92.      bbbb    When creating a new file force information be written with Big-
  93.           Endian byte order (but see below).  By default the library will
  94.           create new files using the native CPU byte order.
  95.  
  96.      LLLL    Force image data that is read or written to be treated with bits
  97.           filled from Least Significant Bit (LSB) to Most Significant Bit
  98.           (MSB).  Note that this is the opposite to the way the library has
  99.           worked from its inception.
  100.  
  101.      BBBB    Force image data that is read or written to be treated with bits
  102.           filled from Most Significant Bit (MSB) to Least Significant Bit
  103.           (LSB); this is the default.
  104.  
  105.      HHHH    Force image data that is read or written to be treated with bits
  106.           filled in the same order as the native CPU.
  107.  
  108.      MMMM    Enable the use of memory-mapped files for images opened read-only.
  109.           If the underlying system does not support memory-mapped files or if
  110.           the specific image being opened cannot be memory-mapped then the
  111.           library will fallback to using the normal system interface for
  112.           reading information.  By default the library will attempt to use
  113.           memory-mapped files.
  114.  
  115.      mmmm    Disable the use of memory-mapped files.
  116.  
  117.      CCCC    Enable the use of ``strip chopping'' when reading images that are
  118.           comprised of a single strip or tile of uncompressed data.  Strip
  119.           chopping is a mechanism by which the library will automatically
  120.           convert the single-strip [-tile] image to multiple strips [tiles],
  121.           each of which has about 8 Kilobytes of data.  This facility can be
  122.           useful in reducing the amount of memory used to read an image
  123.           because the library normally reads each strip [tile] in its
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))      IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))
  135.  
  136.  
  137.  
  138.           entirety.  Strip chopping does however alter the apparent contents
  139.           of the image because when an image is divided into multiple strips
  140.           it looks as though the underlying file contains multiple separate
  141.           strips [tiles].  Finally, note that strip chopping is an optional
  142.           compile-time feature of the library; just because its use is enabled
  143.           by an application does not mean that it may be present in the
  144.           library.
  145.  
  146.      cccc    Disable the use of strip chopping when reading images.
  147.  
  148. BBBBYYYYTTTTEEEE OOOORRRRDDDDEEEERRRR
  149.      The TIFF specification (aaaallllllll vvvveeeerrrrssssiiiioooonnnnssss) states that compliant readers _m_u_s_t
  150.      _b_e _c_a_p_a_b_l_e _o_f _r_e_a_d_i_n_g _i_m_a_g_e_s _w_r_i_t_t_e_n _i_n _e_i_t_h_e_r _b_y_t_e _o_r_d_e_r.  Nonetheless
  151.      some software that claims to support the reading of TIFF images is
  152.      incapable of reading images in anything but the native CPU byte order on
  153.      which the software was written.  (Especially notorious are applications
  154.      written to run on Intel-based machines.)  By default the library will
  155.      create new files with the native byte-order of the CPU on which the
  156.      application is run.  This ensures optimal performance and is portable to
  157.      any application that conforms to the TIFF specification.  To force the
  158.      library to use a specific byte-order when creating a new file the ``b''
  159.      and ``l'' option flags may be included in the call to open a file; for
  160.      example, ``wb'' or ``wl''.
  161.  
  162. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  163.      Upon successful completion _T_I_F_F_O_p_e_n, _T_I_F_F_F_d_O_p_e_n, and _T_I_F_F_C_l_i_e_n_t_O_p_e_n
  164.      return a TIFF pointer.  Otherwise, NULL is returned.
  165.  
  166. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  167.      All error messages are directed to the _T_I_F_F_E_r_r_o_r(3T) routine.  Likewise,
  168.      warning messages are directed to the _T_I_F_F_W_a_r_n_i_n_g(3T) routine.
  169.  
  170.      """"%%%%ssss"""":::: BBBBaaaadddd mmmmooooddddeeee.  The specified _m_o_d_e parameter was not one of ``r''
  171.      (read), ``w'' (write), or ``a'' (append).
  172.  
  173.      %%%%ssss:::: CCCCaaaannnnnnnnooootttt ooooppppeeeennnn.  _T_I_F_F_O_p_e_n() was unable to open the specified filename
  174.      for read/writing.
  175.  
  176.      CCCCaaaannnnnnnnooootttt rrrreeeeaaaadddd TTTTIIIIFFFFFFFF hhhheeeeaaaaddddeeeerrrr.  An error occurred while attempting to read the
  177.      header information.
  178.  
  179.      EEEErrrrrrrroooorrrr wwwwrrrriiiittttiiiinnnngggg TTTTIIIIFFFFFFFF hhhheeeeaaaaddddeeeerrrr.  An error occurred while writing the default
  180.      header information for a new file.
  181.  
  182.      NNNNooootttt aaaa TTTTIIIIFFFFFFFF ffffiiiilllleeee,,,, bbbbaaaadddd mmmmaaaaggggiiiicccc nnnnuuuummmmbbbbeeeerrrr %%%%dddd ((((0000xxxx%%%%xxxx)))).  The magic number in the
  183.      header was not (hex) 0x4d4d or (hex) 0x4949.
  184.  
  185.      NNNNooootttt aaaa TTTTIIIIFFFFFFFF ffffiiiilllleeee,,,, bbbbaaaadddd vvvveeeerrrrssssiiiioooonnnn nnnnuuuummmmbbbbeeeerrrr %%%%dddd ((((0000xxxx%%%%xxxx)))).  The version field in the
  186.      header was not 42 (decimal).
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.                                                                         PPPPaaaaggggeeee 3333
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200. TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))      IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll       TTTTIIIIFFFFFFFFOOOOppppeeeennnn((((3333TTTT))))
  201.  
  202.  
  203.  
  204.      CCCCaaaannnnnnnnooootttt aaaappppppppeeeennnndddd ttttoooo ffffiiiilllleeee tttthhhhaaaatttt hhhhaaaassss ooooppppppppoooossssiiiitttteeee bbbbyyyytttteeee oooorrrrddddeeeerrrriiiinnnngggg.  A file with a
  205.      byte ordering opposite to the native byte ordering of the current machine
  206.      was opened for appending (``a'').  This is a limitation of the library.
  207.  
  208. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  209.      _l_i_b_t_i_f_f(3T), _T_I_F_F_C_l_o_s_e(3T)
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.                                                                         PPPPaaaaggggeeee 4444
  260.  
  261.  
  262.  
  263.